home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / djgpp / readme.dj < prev    next >
Text File  |  1994-08-07  |  17KB  |  431 lines
  1.  
  2. This is the README file for DJ's GCC port to DOS ("djgpp")
  3.  
  4. Contents:
  5.     * Overview
  6.     * What's available
  7.     * How to install
  8.     * Deviations and Caveats
  9.     * Copyright information
  10.  
  11. Disclaimer: This software is distributed WITHOUT ANY WARRANTY; without
  12. even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  13. PURPOSE.
  14.  
  15. DJ Delorie
  16. USmail: 24 Kirsten Ave, Rochester, NH 03867-2954, USA
  17. email:  dj@ctron.com
  18.  
  19. mailing list: djgpp@sun.soe.clarkson.edu (listserv@sun.soe.clarkson.edu)
  20.      djgpp-announce@sun.soe.clarkson.edu (listserv@sun.soe.clarkson.edu)
  21.      (do not send add/delete messages to djgpp or djgpp-announce)
  22.      (see the file README.1ST for info on joining the mailing list)
  23.  
  24.  
  25.  
  26. Overview:
  27.  
  28. This package contains a 32-bit 80386 DOS extender with symbolic
  29. debugger, a C/C++ compiler with utilities, development libraries, and
  30. source code.  It generates full 32-bit programs and supports full
  31. virtual memory with paging to disk. 
  32.  
  33. Requirements:
  34.  
  35. A 80386-based IBM compatible PC or PS/2, 4Mb of hard drive space (70M
  36. for full install), and 512K RAM.  Available extended (or expanded under
  37. VCPI) memory is strongly recommended. 
  38.  
  39. Supported Wares:
  40.  
  41. * Up to 128M of extended memory (expanded under VCPI)
  42. * Up to 128M of disk space used for swapping
  43. * SuperVGA 256-color mode up to 1024x768
  44. * 80387
  45. * XMS & VDISK memory allocation strategies
  46. * VCPI programs, such as QEMM, DESQview, and 386MAX
  47. * DPMI programs, such as Windows 3.x, OS/2, and QDPMI
  48.  
  49. Unsupported:
  50.  
  51. * Multiprocessing (fork())
  52.  
  53.  
  54.  
  55.  
  56. File location:
  57.  
  58.     host:      oak.oakland.edu (and other Simtel20 mirrors)
  59.     login:     ftp
  60.     password:  send your e-mail address
  61.     directory: pub/msdos/djgpp
  62.  
  63. Many thanks to the Simtel20 people for allowing djgpp to be part of
  64. their archives!
  65.  
  66. NOTE: In accordance with FSF CopyLeft, you are not allowed to upload
  67. this program to a distribution site unless you upload the source modules
  68. with any binary module you upload.  Please read the file COPYING for
  69. more details. 
  70.  
  71. NOTE: If your application links in object modules that were written by
  72. FSF, your application counts as a "derived work" and must obey the
  73. provisions of the FSF Copyrights.  See the file COPYING for details. 
  74. All FSF source-based libraries are in the file libgpl.a and libgpp.a. 
  75. The mere act of compiling does not affect the copyright status of your
  76. program. 
  77.  
  78.  
  79.  
  80.  
  81.  
  82.  
  83.  
  84.  
  85.  
  86. INSTALLING:
  87.  
  88. To install, you must do the following:
  89.  
  90. * Create a "temp" directory, like c:\tmp.
  91.  
  92. * Create a directory to install in, like c:\djgpp.
  93.  
  94. * Un-zip the appropriate zipfiles in the install directory.
  95.     C:\DJGPP> unzip -o djeoe112.zip    (Minimum runtime stuff - required)
  96.     C:\DJGPP> unzip -o djdev112.zip    (Minimum development stuff - required)
  97.     C:\DJGPP> unzip -o gcc257bn.zip    (The C compiler - required)
  98.     C:\DJGPP> unzip -o gas211bn.zip    (The assembler - required)
  99.     C:\DJGPP> unzip -o bnu22bn.zip    (The linker etc - required)
  100.  
  101.     C:\DJGPP> unzip -o djdoc112.zip    (If you want documentation)
  102.     C:\DJGPP> unzip -o txi210bn.zip    (If you want the online doc reader INFO.EXE)
  103.     C:\DJGPP> unzip -o gpp257.zip    (If you want to compile C++)
  104.     C:\DJGPP> unzip -o objc257.zip    (If you want to compile Objective-C)
  105.     C:\DJGPP> unzip -o bsn121bn.zip    (If you want to use bison)
  106.     C:\DJGPP> unzip -o flx238bn.zip    (If you want to use flex)
  107.     C:\DJGPP> unzip -o gzp124bn.zip    (If you want gzip)
  108.  
  109.     C:\DJGPP> unzip -o dj112m1.zip      (Maintainence releases)
  110.     
  111.   The maintainance releases are numbered dj112m1.zip, dj112m2.zip, etc.
  112.   Install them all, in order, after all other modules. 
  113.  
  114.   If you prefer to use pkunzip, use "pkunzip -d -o" instead of "unzip -o".
  115.  
  116.   Note: The file "unzip386.exe" is available from where you got djgpp.
  117.   It is Info-Zip's unzip built with djgpp, and includes a built-in
  118.   copy of go32.exe.
  119.  
  120.   Other .zip files contain various documentation (*dc.zip) and source
  121.   files (*sr.zip, *s1.zip, etc).
  122.  
  123. * If you are installing over an existing djgpp area, make sure you remove
  124.   the files bin/aout2exe.exe and bin/exe2aout.exe.  They have been replaced
  125.   with coff2exe and exe2coff.  Also, some programs may not work correctly
  126.   if using an old version of go32 and/or an old emu387, so be sure to remove
  127.   any old versions of these files.
  128.  
  129. * Add the following lines to C:\CONFIG.SYS file (or edit existing
  130.   files= and shell= lines as appropriate).  The files= line prevents "too many
  131.   open files" errors when compiling, and the shell= line prevents "Out of
  132.   environment space" errors when setting lots of environment variables.
  133.  
  134.     files=15
  135.     shell=c:\command.com c:\ /e:1000 /p
  136.  
  137. The values 15 and 1000 are close to minimal.  You may want to increase them
  138. to provide a little more margin.
  139.  
  140.  
  141. * Add the following lines to C:\AUTOEXEC.BAT:
  142.     set DJGPP=c:/djgpp/djgpp.env
  143.  
  144. * Optionally, add these lines:
  145.  
  146.     set TMPDIR=c:/tmp
  147.              ^^^ this is where gcc's temp files go.  It should be a ramdrive
  148.              if you have one.
  149.     set GO32TMP=c:/tmp
  150.                 ^^^ this is where your paging file goes - if not set, the
  151.                 variables TMP and TEMP are checked in that order.  This
  152.                 should be a real drive.
  153.     set GO32=driver c:/djgpp/drivers/SOMETHING.grd gw 1024 gh 768
  154.                     ^^^ whatever driver works with your VGA (optional)
  155.  
  156.   Remember that unless you manually type these at the command line,
  157.   they won't take effect until you reboot.  Don't include the "ansi"
  158.   keyword in the "go32" variable if you don't have an ANSI.SYS driver
  159.   or equivalent.
  160.  
  161. * Add your binaries directory to your PATH in C:\AUTOEXEC.BAT
  162.     SET PATH= . . . ;c:\djgpp\bin
  163.  
  164. That's it! djgpp is now installed on your system.
  165.  
  166. To try it out, change into the samples/hello directory of the DJGPP
  167. distribution and type "tryit".  If this doesn't work, run "testit",
  168. which will check things out for you. 
  169.  
  170. Note: For some operating systems, such as OS/2 and NT, you may need to
  171. use the 16-bit gcc driver instead of the 32-bit gcc driver.  To do so,
  172. copy the gcc.exe file from utils/gcc-rm/gcc.exe to bin/gcc.exe. 
  173. Don't forget to save the old gcc.exe first!
  174.  
  175.  
  176.  
  177. About the environment
  178.  
  179. If you set the DJGPP environment variable to point to a file, that
  180. file will be used to load the environment.  There is a djgpp.env file
  181. distributed with djgpp that provides most of the values you need.  The
  182. format of the file is like this:
  183.  
  184. VAR=value
  185. VAR=value
  186. [program]
  187. VAR=value
  188. [prog2]
  189. VAR=value
  190.  
  191. Note that all whitespace is preserved, so be careful about trailing
  192. spaces and spaces around the `='.  Variables in the first section
  193. (before any [program] lines) apply to all programs.  Variables in
  194. program-specific sections are loaded only when running that program.
  195. For example, a [gcc] section would have variables that gcc.exe needs.
  196. Values may refer to other variables using the DOS convention, like
  197. %DJGPP%.  In addition, the first characters after the `%' can be used
  198. to process the value before using it.  These syntaxes are allowed:
  199.  
  200.     %variable%     Take the value as is
  201.     %:variable%    Take the directory portion only
  202.     %;variable%    Append with a semicolon if variable is defined
  203.     %/variable%    Replace all `\' with `/'
  204.     %\variable%    Replace all `/' with `\'
  205.     %<variable%    Convert to upper case
  206.     %>variable%    Convert to lower case
  207.  
  208. You may list multiple characters after the %, but they must be before
  209. the variable name, like %:/>DJGPP%.  Variable names are case
  210. sensitive.  The DOS environment variable names are usually upper case.
  211. Variables set through this file override any set in the DOS
  212. environment, unless the first character of the variable name is `+',
  213. in which case the DOS environment overrides the file (the `+' is
  214. removed from the name), as in `+USER=dosuser'.
  215.  
  216.  
  217. The GO32 environment variable:
  218.  
  219.  
  220. This variable controls the options available in go32.  The syntax of
  221. this variable is:
  222.  
  223.   SET GO32=[parm [value]] [parm [value]] . . .
  224.  
  225. Parameters:
  226.  
  227.   ansi           Use ANSI commands to control the color in edebug32
  228.   mono           Use the Monochrome monitor for debugging - useful when
  229.                    debugging graphics applications
  230.   topline        Display status information on the top line of the screen
  231.                  (or the top of the mono monitor)
  232.   1rm            Redirect stdout (file #1) to the monochrome monitor
  233.   2rm            Redirect stderr (file #2) to the monochrome monitor
  234.   1r2            Redirect stdout (file #1) to stderr (file #2)
  235.   2r1            Redirect stderr (file #2) to stdout (file #1)
  236.   nodpmi         don't use dpmi even if you find it.
  237.   core [file]    append exception traceback to the named file.
  238.  
  239.   glob           enable globbing (default)
  240.   noglob         disable globbing
  241.  
  242.   emu [path]     Use the specified file as the 80387 emulator
  243.  
  244.   driver [path]  Use the specified file as the graphics driver
  245.   gw [width]     Default graphics width
  246.   gh [height]    Default graphics height
  247.   tw [width]     Default text width
  248.   th [height]    Default text height
  249.   nc [colors]    Number of colors (for new-style drivers only - see cbgrx*.zip)
  250.  
  251.  
  252. These parameters may occur in any order.
  253.  
  254. Note that "1rm" and "2rm" are done before "1r2" and "2r1", so "1rm 2r1" sends
  255. stdout to the mono monitor and stderr to any redirection used.
  256.  
  257. Examples:
  258.  
  259.   C:\> set GO32=mono driver c:\djgpp\drivers\tseng4k.grd gw 1024 gh 768 tw 132 th 43 nc 256
  260.   C:\> set GO32=ansi
  261.   C:\> set GO32=driver c:\djgpp\drivers\tseng4k.grd ansi
  262.   C:\> set GO32=mono 1rm 2rm nodpmi topline
  263.  
  264.  
  265.  
  266.  
  267. Debugging:
  268.  
  269. To debug your code, compile with "gcc -g".  Then, run the executable
  270. with a line like this:
  271.  
  272.   C:\> go32 -d edebug32 myprog        (for non-DPMI)
  273.   C:\> go32 -d ed32-dpmi myprog       (for DPMI)
  274.  
  275. See the docs/djgpp/edebug32.doc file for information on edebug32 commands.
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284. Deviations and Caveats:
  285.  
  286. GCC/G++ deviates from the U**x version in a number of ways, mostly to
  287. accomodate deficiencies in the MS-DOS environment, and my own laziness.
  288.  
  289. * An 80387 is required to do floating point.  An emulator is provided.
  290.   cc1 and cc1plus shouldn't use the 387 unless compiling floating point
  291.   code.  The environment variable "387" can override the auto-detection
  292.   routine:
  293.     SET 387=YES   to force 387 handlers to be enabled
  294.     SET 387=NO    to force 387 accesses to fault
  295.     SET 387=QUERY to get a message showing the results of the auto-detection
  296.   If no 80387 is present and the program attempts to use it, a message
  297.   indicating where the instruction is will be displayed.  To use the
  298.   387 emulator, add "emu c:\djgpp\bin\emu387" to the GO32 environment
  299.   variable.  Specifying use of the emulator overrides the "387"
  300.   environment variable and autodetection code.
  301.  
  302. * The VDISK method of allocating extended memory is supported.  The
  303.   INT 15h method is also.  When the extender runs out of conventional and
  304.   extended memory, it uses a paging file named $(GO32TMP)/pgXXXXXX.386, where
  305.   XXXX is an unspecified hex value.  This file is normally removed on exit.
  306.  
  307. * Up to 128 MB of physical memory and 128 MB of disk swap space are allowed.
  308.   A 512K machine is sufficient, but very slow due to paging.
  309.  
  310. * The utilies support the MS-DOS standard response file method for giving
  311.   more than 128 bytes of command line.  Example: "gcc -o foo @foo.lnk" where
  312.   foo.lnk contains a list of .o files.  Wildcard expansion (globbing) is
  313.   performed on the parameters, unless they are surrounded by quotes. Quotes
  314.   can be used to prevent spaces from separating arguments, much like Unix.
  315.   Also supported is the GNUish-DOS method of passing arguments in
  316.   environment variables.
  317.  
  318. * Since MS-DOS does not distinguish case in file names, some .h files
  319.   used for C++ have had underscores prepended to them to avoid conflict
  320.   (ie: String.h conflicts with string.h, so it became _String.h).
  321.  
  322. * The extender can be merged to create one .exe file that is the extender
  323.   and the executable in one file, by using the stub.exe program:
  324.     coff2exe myprog   (this merges stub.exe, and go32.exe is still required)
  325.     coff2exe -s go32.exe myprog   (this merges go32.exe)
  326.   The first case will only work if go32.exe is in your search path, because
  327.   stub.exe runs it.  Alternatively, you can prepend go32.exe itself to an
  328.   COFF file to get a single executable (stub.exe is much smaller).  Note
  329.   that if you re-compile go32 or stub, you must strip off the symbol table
  330.   first.  Also note that coff2exe is designed to align the executable
  331.   image for better performance, so coff2exe'd programs will run faster
  332.   than those built with copy /b.
  333.  
  334. * The extender runs programs at logical address 0.  A copy of the first
  335.   1 MB of physical memory (including the AT channel) is mapped to
  336.   0xE0000000 in the program's address space.  The stack grows down from
  337.   0x7FFFFFFC in the program's address space.  These numbers will be
  338.   different under DPMI.  You should use <sys/farptr.h> or dosmemget/dosmemput
  339.   to access DOS memory portably.
  340.  
  341. * The paging mechanism understands how SuperVGA's map their memory onto
  342.   the AT bus and automatically swaps pages as the program tries to
  343.   access them.  The program sees a linear range from 0xD0000000 to
  344.   0xD0100000 that corresponds to each pixel in the 256-color modes
  345.   of SuperVGAs.  To use this feature, you'll have to set the GO32
  346.   environment variable like this:
  347.     C>set go32=driver c:\djgpp\drivers\tseng4k.grd gw 640 gh 480 tw 132 th 43
  348.   These parameter pairs can be omitted or rearranged as needed.  They are
  349.   the "driver" name, default graphics width and height, and default
  350.   text width and height. Libgr.a doesn't have to be recompiled, nor
  351.   do graphics programs, when a different graphics mode is selected
  352.   (the extender handles it).  It is strongly recommended that the program
  353.   use the GR_default_graphics and GR_default_text modes to switch to
  354.   graphics or text.  These modes use the parameters specified by the
  355.   GO32 environment variable, allowing the user to select a favorite
  356.   graphics and text mode.  Note that this isn't available in DPMI.
  357.  
  358. * Signals are not reported to the program.  However, interrupts do continue
  359.   to get serviced while in protected mode (ie: keypress, timer, etc).
  360.   CTRL-C will get you back to the external debugger, and you can continue
  361.   from where you stopped.  All signals (ie: exceptions) cause debugging
  362.   traps in the external debugger, or general faults in go32.
  363.  
  364.  
  365.  
  366. Copyright Information:
  367.  
  368. * Source code for the GNU utilities is copyright (c) Free Software Foundation.
  369.   For more information on the FSF copyright, see their source code or write
  370.   Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  371.  
  372.   A copy of their file "COPYING" is included in the docs directory.  Some of
  373.   the FSF source code has been modified to operate properly in the MS-DOS
  374.   environment.
  375.  
  376. * Source code for most of libc.a are copyright (c) Regents of the University
  377.   of California.  These files include copyright information in them.  The
  378.   utilities are compiled against these libraries, and thus contain software
  379.   developed by the University of California, Berkeley, and its contributors.
  380.   Some of the BSD source code has been modified to operate properly in the
  381.   MS-DOS environment.
  382.  
  383. * Any sources not falling under the copyrights of FSF or UCB (as above) are
  384.   Copyright (c) 1991 DJ Delorie, 24 Kirsten Ave, Rochester NH 03867-2954.
  385.   To contact me via E-Mail, sent to "dj@ctron.com".  Cabletron Systems Inc
  386.   is in no way involved with this project; I just happen to work for them
  387.   during the day.
  388.  
  389. Terms and Conditions:
  390.  
  391. * Source code copyright FSF is distributed under the terms of the GNU
  392.   Public General License.  See the file "COPYING" in doc.arc for more
  393.   information.  If your program links in object modules (in libgpl.a) that
  394.   are compiled from GNU sources, then your entire program must be
  395.   distributed under the terms of the GNU GPL as a "derived work".  These
  396.   modules are the C++ class library (including the streams classes) and
  397.   obstacks, and are restricted to the libgpl.a and libgpp.a libraries.
  398.   The sources in libsrc have the copyright notices in them for the
  399.   various modules.
  400.  
  401. * Source code copyright UCB is distributed under the terms listed in the
  402.   UCB source code itself.
  403.  
  404. * Source code copyright DJ Delorie is distributed under the terms of
  405.   the file "copying.dj".
  406.  
  407. * Changes to source code copyright BSD or FSF are copyright DJ Delorie, but
  408.   fall under the terms of the original copyright.
  409.  
  410.  
  411.  
  412.  
  413.  
  414. Donations may be made to any of the following:
  415.  
  416.     DJ Delorie
  417.     24 Kirsten Ave
  418.     Rochester, NH  03867-2954
  419.     USA
  420.  
  421.     Free Software Foundation
  422.     675 Mass Ave
  423.     Cambridge, MA  02139
  424.     USA
  425.  
  426.     Computer Systems Research Group
  427.     Computer Science Division, EECS
  428.     University of California
  429.     Berkeley, California  94720
  430.     USA
  431.